chore+docs: tidy the repo layout and split the README - #40
Open
JOhnsonKC201 wants to merge 2 commits into
Open
Conversation
Four things the folder had accumulated, none of which a newcomer could tell
apart from live code by looking:
- `scripts/make-app-icon.js`, `make-tray-icon.js`, `make-ico.js` and
`logo-glyph.js` referenced only each other. `make-logo-icons.js` (`npm run
icon`) has produced every app and tray icon from `assets/logo.png` since the
logo rework, and `make-ico.js` was not wired to anything at all. Removed, and
the two `cat-sprite.js` header comments that pointed a reader at
`make-app-icon.js` now point at `pet-sheet.js`, which is a Node consumer that
still exists.
- `assets/pixelcat-demo.{gif,mp4}` and `assets/pixelcat.ico` survived the
rebrand carrying the old name. Nothing embeds them: the README uses the hero,
gallery and carousel, and the build takes `icon.ico`. That is 588K of binary
in every clone for no reader. The demo recipe that writes the pair keeps
working but now writes `pixelpets-demo.*`, and it is out of `demo:all`, which
the README describes as regenerating the README media and which it was not.
- `extras/` held one file. Lobby Jam standalone is the same kind of thing as the
iPad terminal (run it yourself, it is not part of the app), so it moves to
`tools/lobby-jam/` with a README, and a top-level directory goes away.
- `scripts/` is 15 entry points with no map. `scripts/README.md` groups them and,
more usefully, marks the two that are public surface: `notify.js` and
`install-hook.js` are pasted into other people's CI jobs and cron entries, so
they cannot be moved on a tidying whim.
The README had grown to 693 lines and 38K, which is long enough that the two things a landing page has to do, convince someone to try it and get them running, were buried under reference material they had no reason to read yet. Nine `<details>` blocks is the tell: the page already knew most of itself was not for a first-time reader. So it keeps the hero, the gallery, what the thing does, quick start, controls, agent hooks and privacy, and hands the rest to `docs/`: - `docs/features.md` every interaction, coat, mood, sound and productivity feature, as prose rather than collapsed sections, so it is readable in one pass and findable by search - `docs/architecture.md` how one sprite covers 15 coats, plus the project layout, plus the paths that are public surface and cannot move - `docs/development.md` commands, installer builds, visual QA and the macOS beta checklist, which now has a real anchor to link people at - `docs/custom-coats.md` designing, hand-editing and sharing a coat - `docs/README.md` an index, since `docs/` previously held one file and a folder of art and was easy to mistake for a dead end README goes 693 -> 285 lines with nothing dropped. Three staleness fixes found while moving the text: CONTRIBUTING pointed at `README.md#development` and at `npx eslint src/ tests/` rather than the `npm run lint` CI actually runs, and recommended `npm run sheet` where the headless `npm run poses:cat` is what the pose tests drive; frame-pack.md still claimed 28 coats. `tests/bridge-paths.test.js` asserted the README quotes the real `%TEMP%` bridge filenames, and moving the notify docs would have made it fail, which is the test doing its job. Rather than pin the prose in place it now asserts over the whole user-facing doc set, so a path may live on whichever page suits it but still cannot go undocumented, and it additionally fails a page that quotes a `%TEMP%` bridge file nothing reads.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two passes over how the project reads on GitHub. No app behaviour changes: lint clean, 214 tests green, boot check green.
The layout
extras/lobby-jam.htmltools/lobby-jam/index.html+ READMEtools/ipad-terminal/: run it yourself, not part of the app.scripts/make-app-icon.js,make-tray-icon.js,make-ico.js,logo-glyph.jsmake-logo-icons.js(npm run icon) has produced every icon since the logo rework, andmake-ico.jswas not wired to anything.assets/pixelcat-demo.{gif,mp4},assets/pixelcat.icopixelpets-demo.*.scripts/(15 entry points, no map)scripts/README.mdnpm run demo:allno longer runs the legacydemorecipe, so it now does what the README always said it did: hero, gallery, carousel.Deliberately not moved.
agent-hook.js,scripts/notify.jsandlaunch-pixelpets.vbsare all pasted into other people's hook configs, CI jobs and desktop shortcuts, so tidying them would break real installs.CONTRIBUTING.md/SECURITY.md/CODE_OF_CONDUCT.mdstay in the root too: published release notes linkblob/main/SECURITY.md, and GitHub does not redirect moved files. Both are now written down indocs/architecture.mdso the next tidy does not have to rediscover them.The README
693 lines and 38K, with nine
<details>blocks, which is the page admitting most of itself is not for a first-time reader. It keeps the hero, gallery, what it does, quick start, controls, agent hooks and privacy, and hands the reference material todocs/:docs/features.mdevery interaction, coat, mood, sound and productivity feature, as prose instead of collapsed sectionsdocs/architecture.mdhow one sprite covers 15 coats, the project layout, and the paths that cannot movedocs/development.mdcommands, installer builds, visual QA, and the macOS beta checklist (now with a real anchor to link testers at)docs/custom-coats.mddesigning, hand-editing and sharing a coatdocs/README.mdan index, sincedocs/held one file and a folder of art693 -> 285 lines, nothing dropped.
Staleness fixed on the way through
CONTRIBUTING.mdpointed atREADME.md#development, atnpx eslint src/ tests/rather than thenpm run lintCI runs, and atnpm run sheetwhere the headlessnpm run poses:catis what the pose tests drive.docs/frame-pack.mdstill claimed 28 coats.cat-sprite.jsheader comments pointed a reader at the deletedmake-app-icon.js.One test changed
tests/bridge-paths.test.jsasserted the README quotes the real%TEMP%bridge filenames, and moving the notify docs made it fail. That is the test working. Rather than pin the prose in place, it now asserts over the whole user-facing doc set, so a path can live on whichever page suits it but still cannot go undocumented, and it additionally fails a page that quotes a%TEMP%bridge file nothing reads.Verification
npm run lintcleannpm test214 pass, 0 failnpm run test:bootrenders a frame